Brandon flagged on #2199 that the schema unit tests only assert that
zod accepts the shape and don't prove that an agent-issued
hyperdx_save_dashboard call actually persists a heatmap with every
MCP-specific field. The bare-minimum heatmap test that lands with the
#2200 heatmap external-API work covers only the required
valueExpression; this test drives the full round-trip with
heatmapScaleType, countExpression, numberFormat, where, and
whereLanguage all set, then mutates them on PUT and re-reads to
confirm the new values stick.

Drive-by: drops an em-dash from a sibling test comment to satisfy the
prose-lint hook on this file.

#2200)

## Summary

Heatmap was the only builder-mode display type that did not round-trip through the external dashboards API. The serializer dropped it into the "unsupported" fall-through, so creating, fetching, and updating heatmap tiles via `/api/v2/dashboards` lost the config.

This wires up heatmap end-to-end on the external API: a dedicated select-item schema, an explicit case in both serialization directions, OpenAPI JSDoc, and tests.

Follow-up to #2107 (review feedback from @pulpdrew, who asked whether we had a follow-up ticket to update the external API for the new visualization type).

## What's in the diff

- **Zod schemas** (`packages/api/src/utils/zod.ts`): a heatmap select-item schema that exposes the literal `aggFn: "heatmap"` plus `valueExpression`, optional `countExpression`, `alias`, `heatmapScaleType`; and a heatmap chart-config schema with optional `groupBy` and `numberFormat`. Heatmap is added to the **builder** discriminated union only.
- **Conversion utilities** (`packages/api/src/routers/external-api/v2/utils/dashboards.ts`):
  - Builder serializer: replaces the old `case DisplayType.Heatmap:` fall-through with an explicit case that reads heatmap-specific fields off `config.select[0]` and emits `aggFn: "heatmap"` on the external surface.
  - Builder deserializer: new `case 'heatmap':` mirroring the Pie pattern; maps the external `aggFn: "heatmap"` back to the internal `aggFn: "count"` that the editor form persists, while preserving `countExpression`, `alias`, and `heatmapScaleType` on the select item.
  - The raw-SQL switch is intentionally left untouched: heatmap stays in the unsupported fall-through there because heatmap rendering requires `isBuilderChartConfig`.
- **OpenAPI JSDoc** (`packages/api/src/routers/external-api/v2/dashboards.ts`): `HeatmapSelectItem` and `HeatmapBuilderChartConfig` components, and `heatmap` added to the `TileConfig` `oneOf` and discriminator mapping.
- **Tests** (`packages/api/src/routers/external-api/__tests__/dashboards.test.ts`): heatmap added to the existing "round-trip all supported chart types" tests for both POST and PUT, plus an explicit rejection test confirming raw-SQL heatmap tiles return 400.
- **`packages/api/openapi.json`**: regenerated.

## Notes for review

- No raw-SQL heatmap variant. PR #2107 made heatmap builder-only and `DBDashboardPage.tsx` requires `isBuilderChartConfig` for heatmap rendering, so the raw-SQL fall-through stays.
- `heatmapScaleType` and `countExpression` are persisted on the per-select-item level (via `DerivedColumnSchema` in `packages/common-utils/src/types.ts`), not on the chart config root. The form binds them as `series.0.heatmapScaleType` / `series.0.countExpression`. The schema and conversion utilities follow that.
- The aggFn translation (external `"heatmap"` ↔ internal `"count"`) keeps the saved Mongo document identical to what the editor form produces, so heatmap tiles created via the API render the same way as ones created via the UI.

## Tier

Lands as `review/tier-4` because anything under `packages/api/src/routers/external-api/` is on the critical-path list. Diff is ~250 prod lines (most of it OpenAPI JSDoc and Zod boilerplate); no schema migrations or auth changes.

## Test plan

- [x] `make ci-lint` (yarn lint, tsc --noEmit, OpenAPI lint)
- [x] `make ci-unit` (common-utils + app)
- [ ] CI runs the full integration suite (heatmap round-trip POST + PUT + raw-SQL rejection); local `make dev-int` requires Docker BuildKit which isn't available on this host.

## Deep-review carryover (2026-05-07)

- **Resolved here**: P0/P1 #4 (`convertToInternalTileConfig` comment vs `applyHeatmapDefaults` reality, see commit `946412ad`).
- **Resolved in #2199**: P0/P1 #1 (heatmap arm in `mcpTilesParam`) already shipped; P0/P1 #3 (heatmap entry in `buildQueryGuidePrompt` + `buildCreateDashboardPrompt`) added in commit `e583fc68`.
- **Pending in #2199 post-rebase**: P0/P1 #2 (MCP `createDashboard`/`updateDashboard` calling `getHeatmapTilesWithIncompatibleSources`), since the helper is added in this PR and not yet importable from #2199's branch.
- **Deferred (P2)**: heatmap GET fallthrough silently rewriting to line on malformed docs, and source-kind-change wedge on PUT. Both tracked in #2236.